#///////////////////////////////////////////////////////////////////////////////
## .. module:: file2doc 
#
# From a source code file, generate documentation.  
#
# The source file should
# contain restructured text markup, optionally enhanced by the
# `Sphinx markup <http://sphinx.pocoo.org>`_. All comments to be considered as
# documentation should be surrounded by lines beginning with ``##``. 
#   
# Two things happen: 
#
# 1. An html page is generated based on the RST, and this page links
# 2. A copy of the raw source file.
# 
# Parameters
# !!!!!!!!!!
#   FILENAME
#       the file you want to document.  This should be given as a
#       path relative to the 'source' directory (e.g.
#       quantitativesustainability/qtsa/trunk/source/main/plot/plot.R ->
#       main/plot/plot.R).
#
# Configuration
# !!!!!!!!!!!!!
# Set rootDir to the directory in which your quantitativeSustainability 
# repository sits: ``rootDir=/home/myself/code/``
#
# You may also have to modify ``sourceRootDir``, and ``docsDir``, depending 
# on which folder you checked out from the repository.
#   
# Command-line usage
# !!!!!!!!!!!!!!!!!!
# ::
#
#   source source2doc.sh FILENAME
#
# .. warning::
#     File setup assumes that you are running from the head of the source tree.
#
# .. codeauthor:: Joe Kwiatkowski
##
#///////////////////////////////////////////////////////////////////////////////
# THESE BITS YOU MIGHT HAVE TO CONFIGURE.
#
# Where you've installed the repository:
rootDir=~/code
#
# The directory where the code is stored: 
sourceRootDir=${rootDir}/quantitativesustainability/qsta/trunk/source
# The directory where the docs are stored:
docsRootDir=${rootDir}/quantitativesustainability/qsta/trunk/docs/source

sourceDocsDir=source/docs
sourceCodeDir=source/code
#///////////////////////////////////////////////////////////////////////////////

fullFileName=$1  # The file we're going to document (see FILENAME above):
fileName=$(basename $fullFileName) # The filename without it's path.

outputDocsDir=${docsRootDir}/${sourceDocsDir}/${fullFileName%$fileName}
outputDocsFile=${docsRootDir}/${sourceDocsDir}/${fullFileName}.rst

outputCodeDir=${docsRootDir}/${sourceCodeDir}/${fullFileName%$fileName}
outputCodeFile=${docsRootDir}/${sourceCodeDir}/${fullFileName}.rst

#...............................................................................
# Copy code to $sourceCodeDir.
#...............................................................................
mkdir -p ${outputCodeDir}3

# Add a title:
title="$fullFileName source"
title=${fullFileName}" source"          
titleLine=$(echo $title | sed s/./=/g)
echo $titleLine > $outputCodeFile 
echo $title >> $outputCodeFile 
echo $titleLine >> $outputCodeFile 

# Add a link back to documentation:
echo ":doc:\`(---> see just documentation) </${sourceDocsDir}/${fullFileName}>\`" \
    >> $outputCodeFile
echo "" >> $outputCodeFile

# Format such that source is shown in RST markup:
echo "::" >> $outputCodeFile 
echo "" >> $outputCodeFile
sed s/^/\\t/ $fullFileName >> $outputCodeFile

#...............................................................................
# Define docs in $sourceDocsDir:
#...............................................................................
mkdir -p ${outputDocsDir}

# Add a title which links to code file:
title="$fullFileName documentation"
titleLine=$(echo $title | sed s/./=/g)
echo $titleLine > $outputDocsFile
echo $title >> $outputDocsFile
echo $titleLine >> $outputDocsFile
echo "" >> $outputDocsFile

# Add a link back to documentation:
echo ":doc:\`(---> see source file) </${sourceCodeDir}/${fullFileName}>\`" \
    >> $outputDocsFile
echo "" >> $outputDocsFile

# Strip documentation out of source:
sed -n '/^##/,/^##/p' $fullFileName | sed -e s/^##// -e s/^#\ // -e s/^#// \
    >> $outputDocsFile 
